Library Integration for IMU - Calibration Container

![]() |
![]() |
Introduction
Calibrated cameras offer two advantages when working with video stabilization:
- The intrinsic camera matrix is used to convert between real-world coordinates and image space dimensions.
- The distortion parameters are used to remove distortion from images caused by camera lens.
We explain the calibration theory in this article in more detail.
The RidgeRun Video Stabilization Library provides a camera calibration tool to obtain the intrinsic camera matrix and distortion parameters. In order to simplify the construction and usage of the camera calibration tool, we also provide a docker container that runs the calibration tool on a set of samples and provides the resulting calibration data.
Building the Calibration Container Image
Dependencies
- Compulsory dependencies: Make sure to have the compulsory dependencies for the RidgeRun Video Stabilization Library.
- Docker: Additionally, Docker is used to build and run the calibration container. To install Docker, follow these guides:
Build Steps
Once the code for the video stabilizer library has been obtained, follow these steps from the project root to build the docker image for the calibration container:
- Obtain the project submodules:
git submodule update --init --recursive meson subprojects download
- Build the docker image:
export DOCKER_BUILDKIT=1 docker build -f ./docker/Dockerfile -t ridgerun/video-stabilization-library:cameracalibrator_latest .
Using the Calibration Container
To use the calibration container, the host must first have a directory that is going to be mounted as a volume on the container and where the calibration results will be stored. In the following commands, replace </path/to/host-volume>
with the absolute path to this directory.
This directory must contain a subdirectory named samples
that contains all the calibration samples. These samples are expected to be jpg files.
Below we instructions for using the calibration container in 4 different configurations:
- Default Configuration
- Configuring Calibration Technique
- Interactive Sample Selection
- Previewing Samples
We also provide an example where we combine configurations:
Default Configuration
Run the calibration container with:
docker run --rm --name calibration-container --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume ridgerun/video-stabilization-library:cameracalibrator_latest
This will save a calibration.yml
file in the mounted volume with the calibration data. Additionally a samples-undistorted
subdirectory will be created in the mounted volume and it will contain all the undistorted samples.
Configuring Calibration Technique
To specify the calibration technique, run the calibration container with:
docker run --rm --name calibration-container --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume ridgerun/video-stabilization-library:cameracalibrator_latest -t <technique>
Replace <technique>
with the desired technique. The available techniques are:
fisheye
: This is the default technique and it uses the fisheye lens model to calibrate the samples.brown
: This uses the Brown-Comrady lens model to calibrate the samples.
Interactive Sample Selection
To interactively select samples, run the calibration container with:
docker run --rm --name calibration-container --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume -it ridgerun/video-stabilization-library:cameracalibrator_latest
This allows the use of the following commands to select samples used for calibration:
ENTER
: Selects the samplen + ENTER
: Discards the sampleq + ENTER
: Ends the sample selection and starts the calibration
Previewing Samples
To preview the samples during the sample selection step (assuming the host uses the X window system), run the calibration container with:
xhost +local: docker run --rm --name calibration-container -e DISPLAY=$DISPLAY --mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix,readonly --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume ridgerun/video-stabilization-library:cameracalibrator_latest -p
These commands allows the container access to the X server on the host so that it can open a preview window.
Combining Configurations
The previous configurations can be combined to customize the calibration experience. For example, the following commands use the Brown-Comrady lens model to calibrate, they allow the user to interactively select samples, and they display a preview of the samples during the selection step:
xhost +local: docker run --rm --name calibration-container -e DISPLAY=$DISPLAY --mount type=bind,src=/tmp/.X11-unix,dst=/tmp/.X11-unix,readonly --mount type=bind,src=</path/to/host-volume>,dst=/root/host-volume -it ridgerun/video-stabilization-library:cameracalibrator_latest -p -t brown